<HTML>
  <HEAD>
    <TITLE>threadpool Documentation</TITLE>
    <LINK HREF="threadpool.css" REL="stylesheet" TYPE="text/css">
  </HEAD>
  <BODY BGCOLOR="#FFFFFF">

    <DIV CLASS="qindex">
      <TABLE BORDER="0" WIDTH="100%">
        <TR>

          <TD ALIGN="LEFT">
            <B>threadpool</B>
          </TD>
          <TD ALIGN="RIGHT">
            <A CLASS="qindex" HREF="../index.html">Overview</A> |
            <A CLASS="qindex" HREF="../reference/annotated.html">Reference</A> |
            <A CLASS="qindex" HREF="../tutorial/intro.html">Tutorial</A> |
            <A CLASS="qindex" HREF="../examples/intro.html">Examples</A> |
            <A CLASS="qindex" HREF="../design/intro.html">Design</A>
          </TD>

        </TR>
      </TABLE>
    </DIV>
    <DIV CLASS="qindex">
      <TABLE BORDER="0" WIDTH="100%">
        <TR>
          <TD ALIGN="LEFT">
            <B>Tutorial</B>
          </TD>
          <TD ALIGN="RIGHT">
            <A CLASS="qindex" HREF="intro.html">Quick Start</A> |
            <A CLASS="qindex" HREF="prioritized.html">Prioritized Tasks</A> |
            <A CLASS="qindex" HREF="task_adaptor.html">Arbitrary Task Functions</A> |
            <A CLASS="qindex" HREF="instantiation.html">Advanced Pool Instantiation</A>            
          </TD>
        </TR>
      </TABLE>
    </DIV>
<!-- Generated by Doxygen 1.6.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="contents">


<h1><a class="anchor" id="intro">Quick Start </a></h1><p>This tutorial introduces the threadpool library by discussing an easy to understand source listing:</p>
<div class="fragment"><pre class="fragment">01 
02  #include <span class="stringliteral">&quot;threadpool.hpp&quot;</span>
03
04  <span class="keyword">using namespace </span>boost::threadpool;
05
06  <span class="comment">// Some example tasks</span>
07  <span class="keywordtype">void</span> first_task()
08  {
09    ...
10  }
11
13  <span class="keywordtype">void</span> second_task()
14  {
15    ...
16  }
17
19  <span class="keywordtype">void</span> third_task()
20  {
21    ...
22  }
23  
24  <span class="keywordtype">void</span> execute_with_threadpool()
25  {
26    <span class="comment">// Create a thread pool.</span>
27    pool tp(2);
28    
29    <span class="comment">// Add some tasks to the pool.</span>
30    tp.schedule(&amp;first_task);
31    tp.schedule(&amp;second_task);
32    tp.schedule(&amp;third_task);
33
34    <span class="comment">// Leave this function and wait until all tasks are finished.</span>
35  }
36
</pre></div><p>We start by including the necessary header files. The complete threadpool functionality can be used by simply including the "threadpool.hpp" header file at line 2.</p>
<p>The three functions first_task(), second_task and third_task() are placeholders for tasks that should be executed by our pool.</p>
<p>The thread pool is created at line 27. The argument indicates the number of initial threads. The new pool contains two threads that is two tasks can be processed in parallel. The pool's threads are sleeping until tasks are added. By default it uses a Fifo scheduling strategy. Fifo is an abbreviation of "first in, first out" and means in this case that the first task which is added is the first that will be executed. Generally this is the expected default behaviour since the tasks are executed in the order they are added to the pool.</p>
<p>In line 30 to 32 the task functions are scheduled asynchronously using the pool's schedule function. A task is registered and it will be executed as soon as one of the pool's threads is idle. It is very important to understand that the task is only scheduled for execution. Schedule returns immediately and there are no guarantees about when the tasks are executed and how long the processing will take. As they are added to a fifo pool with two threads the following is true:</p>
<ul>
<li>the execution of first_task begins first</li>
<li>second_task is started after first_task</li>
<li>third_task is begun at last</li>
<li>a maximum of two tasks may are processed in parallel</li>
<li>each scheduled task will be executed once only</li>
</ul>
<p>The pool reference tp is created in the scope of the function execute_with_threadpool(). When this function returns at line 35 tp goes out of scope and the pool will be destructed. As the default ShutdownPolicy is wait_for_all_tasks it is ensured that all tasks are processed before the pool is destroyed.</p>
<div class="fragment"><pre class="fragment">101  
102  ...
103  execute_with_threadpool();  <span class="comment">// execute first_task, second_task and third_task</span>
104  <span class="comment">// When this line is reached all tasks are finished and the pool is destructed.   </span>
105  
</pre></div><p>The small code example clarifies the issue. When the function leaves the pool is shut down and waits for the tasks. That means the current thread of execution is blocked at the end of the execute_with_threadpool as long as the processing of tasks is in progress.</p>
<p><br/>
 </p>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

    <BR>
    <DIV CLASS="qindex">
      <TABLE BORDER="0" WIDTH="100%">
        <TR>
		  <TD CLASS="tiny" ALIGN="LEFT">Copyright &copy 2005-2008 Philipp Henkel</TD>
          <TD ALIGN="RIGHT">
            <A CLASS="qindex" HREF="../index.html">Overview</A> |
            <A CLASS="qindex" HREF="../reference/annotated.html">Reference</A> |
            <A CLASS="qindex" HREF="../tutorial/intro.html">Tutorial</A> |
            <A CLASS="qindex" HREF="../examples/intro.html">Examples</A> |
            <A CLASS="qindex" HREF="../design/intro.html">Design</A>
          </TD>
        </TR>       
      </TABLE>
    </DIV>  
  </BODY>
</HTML>
